/*
 * Copyright (c) 2003, 2004, Oracle and/or its affiliates. All rights reserved.
 * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 */

package java.lang;

import java.io.IOException;

/**
 * 可以追加 <tt>char</tt> 序列和值的对象。任何实例旨在接收来自
 * {@link java.util.Formatter} 的格式化输出的类都必须实现 <tt>Appendable</tt> 接口。
 *
 * <p> 要追加的字符应该是有效的 Unicode 字符，如
 * <a href="Character.html#unicode">Unicode 字符表示</a>中所述。
 * 请注意，补充字符可能由多个 16 位 <tt>char</tt> 值组成。
 *
 * <p> Appendable 不一定对多线程访问是安全的。线程安全是扩展和实现此接口的类的责任。
 *
 * <p> 由于此接口可能由具有不同错误处理风格的现有类实现，
 * 因此不能保证错误会传播给调用者。
 *
 * @since 1.5
 */
public interface Appendable {

    /**
     * 将指定的字符序列追加到此 <tt>Appendable</tt>。
     *
     * <p> 根据实现字符序列 <tt>csq</tt> 的类，可能不会追加整个序列。
     * 例如，如果 <tt>csq</tt> 是 {@link java.nio.CharBuffer}，
     * 则要追加的子序列由缓冲区的位置和限制定义。
     *
     * @param  csq
     *         要追加的字符序列。如果 <tt>csq</tt> 为 <tt>null</tt>，
     *         则将四个字符 <tt>"null"</tt> 追加到此 Appendable。
     *
     * @return  对此 <tt>Appendable</tt> 的引用
     *
     * @throws  IOException
     *          如果发生 I/O 错误
     */
    Appendable append(CharSequence csq) throws IOException;

    /**
     * 将指定字符序列的子序列追加到此 <tt>Appendable</tt>。
     *
     * <p> 当 <tt>csq</tt> 不为 <tt>null</tt> 时，调用形式为
     * <tt>out.append(csq, start, end)</tt> 的此方法的行为与以下调用完全相同
     *
     * <pre>
     *     out.append(csq.subSequence(start, end)) </pre>
     *
     * @param  csq
     *         将从中追加子序列的字符序列。如果 <tt>csq</tt> 为 <tt>null</tt>，
     *         则将追加字符，就像 <tt>csq</tt> 包含四个字符 <tt>"null"</tt> 一样。
     *
     * @param  start
     *         子序列中第一个字符的索引
     *
     * @param  end
     *         子序列中最后一个字符之后的字符的索引
     *
     * @return  对此 <tt>Appendable</tt> 的引用
     *
     * @throws  IndexOutOfBoundsException
     *          如果 <tt>start</tt> 或 <tt>end</tt> 为负数，<tt>start</tt>
     *          大于 <tt>end</tt>，或 <tt>end</tt> 大于 <tt>csq.length()</tt>
     *
     * @throws  IOException
     *          如果发生 I/O 错误
     */
    Appendable append(CharSequence csq, int start, int end) throws IOException;

    /**
     * 将指定字符追加到此 <tt>Appendable</tt>。
     *
     * @param  c
     *         要追加的字符
     *
     * @return  对此 <tt>Appendable</tt> 的引用
     *
     * @throws  IOException
     *          如果发生 I/O 错误
     */
    Appendable append(char c) throws IOException;
}
